Day02 - 使用 !reference 更靈活的管理 CI/CD YAML - iT 邦幫忙::一起幫忙解決難題，拯救 IT 人的一天

2025 iThome 鐵人賽

DAY 2

DevOps

GitLab CI 2025：深入玩轉流水線與實戰紀錄系列第 2 篇

Day02 - 使用 !reference 更靈活的管理 CI/CD YAML

17th鐵人賽 gitlab gitlab-ci gitlab ci

墨嗓

團隊兩貓一犬一條龍小隊

2025-09-11 02:54:34

117 瀏覽

分享至

開始的第一篇，我們來談談在 GitLab CI 中 CI/CD YAML 語法中的關於重複利用的語法自 13.3 版以後，比較不一樣的地方。從 13.3 版的年代，我們介紹過利用 hind job、anchor 及 extends 語法來重複利用 .gitlab-ci.yml 中的內容，也提到了可以透過 include 來做 YAML 檔案的拆分，甚至透過 Parallel 來針對只有參數不一樣的工作做簡化。

但似乎還不太夠用，例如 anchor 只能夠在同一個 .gitlab-ci.yml 中的部分區段使用，如果是 include 進來的內容，就無法再使用 anchor。因此 GitLab 後來提出了新的語法 !reference tags 來解決這些問題。

`!reference` 如何使用：

這個語法可以怎麼用呢？首先先以官方手冊上提供的範例，稍作修改後，作為說明：

configs.yml:

.setup:
  script:
    - echo "creating environment"

.gitlab-ci.yml

default:
  image: ubuntu:22.04

include:
  - local: configs.yml

.teardown:
  after_script:
    - echo "deleting environment"

test:
  script:
    - !reference [.setup, script]
    - echo "running my own command"
  after_script:
    - !reference [.teardown, after_script]

上面的這個範例，實際執行後可以得到如下的輸出：

$ echo "creating environment"
creating environment
$ echo "running my own command"
running my own command
Running after_script 00:00
Running after script...
$ echo "deleting environment"
deleting environment
Cleaning up project directory and file based variables 00:01
Job succeeded

從上面的範例中，可以看到主要的 JOB：

test:
  script:
    - !reference [.setup, script]
    - echo "running my own command"
  after_script:
    - !reference [.teardown, after_script]

其中 !reference [.setup, script] 取得了 include 進來的 configs.yml 中的 .setup job 中的 script 區段。另外 !reference [.teardown, after_script] 的部分則是使用了同在 .gitlab-ci.yml 中的 .teardown job 中的 after_script 區段，因此解析之後，可以得到如下的結果：

test:
  script:
    - echo "creating environment"
    - echo "running my own command"
  after_script:
    - echo "deleting environment"

可以發現，這樣的語法相當的靈活，尤其是在 script 區段中的運用，一個程度上，可以把一些常用的語法，變成像函式一樣的效果，靈活取用。

`!reference` 使用上的限制

!reference 語法支援槽狀的結構使用，但是最多支援 10層的巢狀使用。以官方提供的範例稍微修改，可以如下的巢狀結構來使用：

default:
  image: ubuntu:22.04

.snippets:
  one:
    - echo "ONE!"
  two:
    - !reference [.snippets, one]
    - echo "TWO!"
  three:
    - !reference [.snippets, two]
    - echo "THREE!"

nested-references:
  script:
    - !reference [.snippets, three]

在這個範例中，會在 nested-references JOB 中會依序輸出 ONE!、TWO! 及 THREE!：

$ echo "ONE!"
ONE!
$ echo "TWO!"
TWO!
$ echo "THREE!"
THREE!

已知問題：

由於 !reference 這個語法，是 GitLab 官方所提出的語法，所以不見得所有的 YAML 檔案編輯器都可以支援，目前除 GitLab 內建的pipeline editor 直接可以識別外，如果要讓編輯器可以支援 !reference tags 語法的話，可以參考 Configure your IDE to support !reference tags的說明。

另外，在官方的手冊上也有提到，當使用 !reference tags 的時候在搭配 parallel:matrix 語法的時候有已知的 known issue，要特別注意。

總結：

過去我們主要依靠 anchor、extends 與 include 來重用設定，但這些方法仍有限制，例如 anchor 無法跨檔案引用。為解決這些問題，GitLab 推出了更靈活的 !reference 語法，讓我們可以像「函式」一樣直接取用其他 job 的區段，無論來自同一檔案或是 include 進來的內容，皆能有效重組 pipeline。透過 !reference，不僅提升了配置的可讀性與維護性，也支援巢狀結構（最多十層），讓 CI/CD 更具彈性。我是墨嗓（陳佑竹），期待這次的內容能帶給你實用的啟發與幫助。